
//
// 110305 - AH - Created.
// 110313 - AH - populateBeforeRetrieval().
// 110617 - AH - (Bybanen *) setPopulate(boolean), getPopulate() and 
//               doPopulate().
//

package org.soekrat.engine.sparewheel.ontology;

import java.util.List;

import org.soekrat.AttributeObject;
import org.soekrat.engine.sparewheel.SpareWheel;
import org.soekrat.engine.visitor.Input;
import org.soekrat.engine.visitor.Lines;
import org.soekrat.engine.wheel.retrieval.RetrievalEvent;

/**
 * <p>
 *   Ontology for the 
 *   {@link SpareWheel}.
 * </p>
 * @author Arne Halvorsen (AH)
 */
public abstract class SpareWheelOntology 
{
  private boolean m_populate=true;
  
  /**
   * <p>
   *   Constructor.
   * </p>
   */
  protected SpareWheelOntology(){}
  
  /**
   * <p>
   *   Tells if to populate ontologies {@code this} before retrieval.
   * </p>
   * <p>
   *   This implements the default which is to return {@code true}, override
   *   if is correct to return {@code false}.
   * </p>
   * @return {@code true} if to populate before, {@code false} if is to 
   *         populate after. 
   */
  public boolean populateBeforeRetrieval(){ return true; }
  
  /**
   * <p>
   *   Sets if should populate.
   * </p>
   * @param v {@code true} if should populate, {@code false} if should not.
   */
  public final void setPopulate(boolean v){ m_populate=v; }
  
  /**
   * <p>
   *   Gets if populates.
   * </p>
   * @return {@code true} if populates, {@code false} if does not.
   */
  public final boolean getPopulate(){ return m_populate; }
  
  /**
   * <p>
   *   Populate the ontology {@code this} access.   
   * </p>
   * @param lines {@link Lines}.
   */
  public final void populate(Lines lines){ if (m_populate) doPopulate(lines); }
  
  /**
   * <p>
   *   Implementations implements to do population.
   * </p>
   * @param lines {@link Lines}.
   */
  protected abstract void doPopulate(Lines lines);
  
  /**
   * <p>
   *   Perform retrieval of information.
   * </p>
   * @param tokens Tokens extracted from visitor's input.
   * @param paint  Where retrieved information is added.
   * @return {@link RetrievalEvent} that is first in sequence that identifies 
   *         steps performed by retrieval algorithm.
   */
  public abstract RetrievalEvent scanAndPaint(Input tokens, 
    List<AttributeObject> paint);
  
  /**
   * <p>
   *   Gets token to pass to another
   *   {@link SpareWheelOntology} given what has been retrieved by {@code this}
   *   {@code SpareWheelSpoke}.
   * </p>
   * @param paint What has been retrieved by {@code this}
   *              {@code Spoke}.
   * @return Tokens.
   */
  public abstract Input getTokens(List<AttributeObject> paint);
    
}
